<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>ControlClick</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>ControlClick</h1>

<p>Sends a mouse  button or mouse wheel event to a  control.</p>

<pre class="Syntax">ControlClick [, Control-or-Pos, WinTitle, WinText, WhichButton, ClickCount, Options, ExcludeTitle, ExcludeText]</pre>
<h3>Parameters</h3>
<dl>

  <dt>Control-or-Pos</dt>
  <dd><p>If this parameter is blank, the target window's topmost control will be clicked (or the target window itself if it has no controls). Otherwise, one of the two modes below will be used.</p>
      <p>Mode 1 (Position): Specify the X and Y coordinates relative to the target window's upper left corner. The X coordinate must precede the Y coordinate and there must be at least one space or tab between them. For example: <code>X55 Y33</code>. If there is a control at the specified coordinates, it will be sent the click-event at those exact coordinates. If there is no control, the target window itself will be sent the event (which might have no effect depending on the nature of the window). Note: In this mode, the X and Y option letters of the <em>Options</em> parameter are ignored.</p>      
      <p>Mode 2 (ClassNN or Text): Specify either ClassNN (the classname and instance number of the control) or the name/text of the control, both of which can be determined via Window Spy. When using name/text, the matching behavior is determined by <a href="SetTitleMatchMode.htm">SetTitleMatchMode</a>.</p>
      <p>By default, mode 2 takes precedence over mode 1. For example, in the unlikely event that there is a control whose text or ClassNN has the format &quot;Xnnn Ynnn&quot;, it would be acted upon by Mode 2. To override this and use mode 1 unconditionally, specify the word Pos in <em>Options</em> as in the following example: <code>ControlClick, x255 y152, WinTitle,,,, Pos</code>.</p>
      <p>To operate upon a control's HWND (window handle), leave this parameter blank and specify <code>ahk_id %ControlHwnd%</code> for the <em>WinTitle</em> parameter (this also works on hidden controls even when <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> is Off). The HWND of a control is typically retrieved via <a href="ControlGet.htm#Hwnd">ControlGet Hwnd</a>, <a href="MouseGetPos.htm">MouseGetPos</a>, or <a href="DllCall.htm">DllCall</a>.</p></dd>

  <dt>WinTitle</dt>
  <dd><p>A window title or other criteria identifying the target window. See <a href="../misc/WinTitle.htm">WinTitle</a>.</p></dd>

  <dt>WinText</dt>
  <dd><p>If present, this parameter must be a substring from a single text element of the target window (as revealed by the included Window Spy utility). Hidden text elements are detected if <a href="DetectHiddenText.htm">DetectHiddenText</a> is ON.</p></dd>

  <dt>WhichButton</dt>
  <dd><p>The button to click: LEFT, RIGHT, MIDDLE (or just the first letter of each of these). If omitted or blank, the LEFT button will be used.</p>
      <p>X1 (XButton1, the 4th mouse button) and X2 (XButton2, the 5th mouse button) are also supported.</p>
      <p>WheelUp (or WU) and WheelDown (or WD) are also supported. In this case, <em>ClickCount</em> is the number of notches to turn the wheel.</p>
      <p>Windows Vista or later <span class="ver">[v1.0.48+]:</span> WheelLeft (or WL) and WheelRight (or WR) are also supported (they have no effect on older operating systems). In this case, <em>ClickCount</em> is the number of notches to turn the wheel.</p>
    </dd>

  <dt>ClickCount</dt>
  <dd><p>The number of clicks to send, which can be an <a href="../Variables.htm#Expressions">expression</a>. If omitted or blank, 1 click is sent.</p></dd>

  <dt>Options</dt>
  <dd><p>A series of zero or more of the following option letters. For example: <code>d x50 y25</code>.</p>
      <p><strong>NA</strong> <span class="ver">[v1.0.45+]:</span> May improve reliability. See <a href="#Reliability">reliability</a> below.</p>
      <p><strong>D</strong>: Press the mouse button down but do not release it (i.e. generate a down-event). If both the <strong>D</strong> and <strong>U</strong> options are absent, a complete click (down and up) will be sent.</p>
      <p><strong>U</strong>: Release the mouse button (i.e. generate an up-event). This option should not be present if the <strong>D</strong> option is already present (and vice versa).</p>
      <p><strong>Pos</strong>: Specify the word Pos anywhere in <em>Options</em> to unconditionally use the X/Y positioning mode as described in the <em>Control-or-Pos</em> parameter above.</p>
      <p><strong>Xn</strong>: Specify for <strong>n</strong> the X position to click at, relative to the control's upper left corner. If unspecified, the click will occur at the horizontal-center of the control.</p>
      <p><strong>Yn</strong>: Specify for <strong>n</strong> the Y position to click at, relative to the control's upper left corner. If unspecified, the click will occur at the vertical-center of the control.</p>
      <p>Use decimal (not hexadecimal) numbers for the <strong>X</strong> and <strong>Y</strong> options.</p></dd>

  <dt>ExcludeTitle</dt>
  <dd><p>Windows whose titles include this value will not be considered.</p></dd>

  <dt>ExcludeText</dt>
  <dd><p>Windows whose text include this value will not be considered.</p></dd>

</dl>

<h3>ErrorLevel</h3>
<p><span class="ver">[v1.1.04+]</span> This command is able to throw an exception on failure. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 if there was a problem or 0 otherwise.</p>
<h3 id="Reliability">Reliability</h3>
<p>To improve reliability -- especially during times when the user is physically moving the mouse during the ControlClick -- one or both of the following may help:</p>
<p>1) Use <code><a href="SetControlDelay.htm">SetControlDelay -1</a></code> prior to ControlClick. This avoids holding the mouse button down during the click, which in turn reduces interference from the user's physical movement of the mouse.</p>
<p>2) Specify the string NA anywhere in the sixth parameter (<em>Options</em>) as shown below:</p>
<pre>SetControlDelay -1
ControlClick, Toolbar321, WinTitle,,,, NA</pre>
<p><code>NA</code> avoids marking the target window as active and avoids merging its input processing with that of the script, which may prevent physical movement of the mouse from interfering (but usually only when the target window is not active). However, this method might not work for all types of windows and controls.</p>
<h3>Remarks</h3>
<p>Not all applications obey a <em>ClickCount</em> higher than 1 for turning the mouse wheel. For those applications, use a Loop to turn the wheel more than one notch as in this example, which turns it 5 notches:</p>
<pre>Loop, 5
    ControlClick, <i>Control</i>, <i>WinTitle</i>, <i>WinText</i>, WheelUp</pre>
<p>Window titles and text are case sensitive. Hidden windows are not detected unless <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> has been turned on.</p>

<h3>Related</h3>
<p><a href="SetControlDelay.htm">SetControlDelay</a>, <a href="Control.htm">Control</a>, <a href="ControlGet.htm">ControlGet</a>, <a href="ControlGetText.htm">ControlGetText</a>, <a href="ControlMove.htm">ControlMove</a>, <a href="ControlGetPos.htm">ControlGetPos</a>, <a href="ControlFocus.htm">ControlFocus</a>, <a href="ControlSetText.htm">ControlSetText</a>, <a href="ControlSend.htm">ControlSend</a>, <a href="Click.htm">Click</a></p>
<h3>Examples</h3>
<pre class="NoIndent">ControlClick, OK, Some Window Title  <em>; Clicks the OK button</em>
ControlClick, x55 y77, WinTitle  <em>; Clicks at a set of coordinates. Note the lack of a comma between X and Y.</em>

<em>; The following method may improve reliability and reduce side effects:</em>
SetControlDelay -1
ControlClick, Toolbar321, WinTitle,,,, NA x192 y10  <em>; Clicks in NA mode at coordinates that are relative to a named control.</em></pre>

</body>
</html>
